PDXPP -- The Paradox Class Libraries for C++ Functional Documentation Overview The PDXPP class library allows the programmer to access the Paradox Engine using C++ class objects. This not only allows the programmer to maintain an object-oriented programming approach, but also hides many of the mundane tasks of using the Paradox Engine. The PDXPP class library was written by Gary B. Weinfurther. It is released into the public domain. No warranties, expressed or implied, are given with the library. The author is not responsible for the results, or lack therof, obtained from the use or disuse of this library. There are five classes within the PDXPP library: PXOBJ - Abstract base class for the other PDXPP classes. PXTABLE - Table-based operations. PXFIELD - Field-based operations. PXRECORD - Operations with record transfer buffers. PXLOCK - Record-locking operations. This documentation, as well as this library, assumes prior knowledge of C++ and of the Paradox Engine. In fact, this library does not attempt to replace the entire functionality of the Paradox Engine; doing so would not be of any necessary benefit to the programmer. Instead, the purpose of the PDXPP library is to allow the manipulation of tables, fields, and records through C++ objects. Not all of the functions within the Paradox Engine have corresponding functions in this library. Primarily, those functions which manipulate the Paradox Engine environment or perform file-level operations are not duplicated, and should be called directly. A list of these functions is given in Appendix 1. Class PXOBJ This is the base class of all of the PDXPP classes. It provides an error-checking mechanism and a table handle for all derived classes. Member functions include: TABLEHANDLE TblHandle(); Returns the table handle of the object. int Result(); Returns the error code of the last operation on this object. This is a Paradox Engine error code. char *ErrMsg(); Returns a pointer to a string containing an error message describing the result of the last operation on this object. Object Evaluation The ! operator and the (void *) operator have been overloaded so you can test an instance of the PXOBJ or a derived class for validity. A non-zero result indicates that the last operation on the object was successful. A zero result indicates that the last operation was not successful, and you should examine the result of Result() or ErrMsg() to determine the cause of the error. For example: PXTABLE mytable("mytable"); if(!mytable) { cout << mytable.ErrMsg(); exit(mytable.Result()); } Class PXTABLE This class is used to represent a Paradox table. An object of this class may be defined to open an existing table or to create a new table. Destruction of a PXTABLE object causes the associated table to be closed. Constructors: PXTABLE(char *name, int index = 0, int saveEveryChange = FALSE); Use this constructor to open an existing table. Refer to the PXTblOpen() function in the Paradox Engine for information on the index and saveEveryChange parameters. PXTABLE(char *name, int nFlds, char **fldnames, char **types, int saveEveryChange = FALSE); Use this constructor to create a new table. Once created, the table will be opened. Be sure to test for success. Methods: int Name(int bufSize, char *namestr); Retrieves the name of the table. bufSize is the lenth of the buffer which namestr points to. RECORDNUMBER NRecs(); Returns the number of records in the table. int NFlds(); Returns the number of fields in the table. int KeyNFlds(); Returns the number of key fields in the table. int RecLocked(); Returns a non-zero value if the current record in the table is locked. int Changed(); Tests whether the table has been changed. int Lock(int lockType); Places a lock of the specified type on the entire table. Returns the Paradox Engine error code (0 = success). int Unlock(int lockType); Removes a lock of the specified type from the table. Returns the Paradox Engine error code. int Refresh() Re-synchronizes the table. Returns the Paradox Engine error code. int RecDelete(); Deletes the current record from the table. The current record can be selected with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. int First(); Moves the current record pointer to the first record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD clas, so use caution. Returns the Paradox Engine result code. int Last(); Moves the current record pointer to the last record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. int Next(); Moves the current record pointer to the next record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. int Prev(); Moves the current record pointer to the previous record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. RECORDNUMBER RecNum(); Returns the current record number. Because Paradox is a multi-user database, this number may not reflect the same data at different times, so use with caution. int Goto(RECORDNUMBER recnum); Moves the current record pointer to the specified record number. Returns the Paradox Engine result code. Class PXFIELD This class is used to represent fields within a table. Create an object of this type for each field you wish to access. Constructors: PXFIELD(PXTABLE &pxtable, char *fldname); Creates a PXFIELD object using a PXTABLE object. Specify the PXTABLE object and the name of the field. PXFIELD(TABLEHANDLE th, char *fldname); Creates a PXFIELD object using a table handle. Specify the table handle and the name of the field. FIELDHANDLE FldHandle(); Returns the field handle of the object. int FldName(int bufSize, char *buffer); Retrieves the name of the field. is the maximum length of the buffer to which points. int FldBlank(); Tests if the field value for the current record is blank. The current record pointer can be moved by an object of either the PXTABLE class or the PXRECORD class, so use caution. int FldType(int bufSize, char *type); Retrieves the field type of the object. is the maximum size of the buffer to which points. Class PXRECORD Objects of this class represent independent record transfer buffers. At least one is required for most table operations. When performing field-level operations, a PXFIELD object or a FIELDHANDLE is required for each individual field to be acted upon. Constructors: PXRECORD(PXTABLE &pxtable); Creates a PXRECORD object for the specified table. PXRECORD(TABLEHANDLE th); Creates a PXRECORD object for the specified table handle. PXRECORD(PXRECORD &sourcerec); Creates a PXRECORD object from an existing PXRECORD object. The new object is tied to the same table as the original object, and the contents of the original record transfer buffer are copied to the new object. Methods: RECORDHANDLE RecordHandle(); Returns the record handle. int NFlds(void); Returns the number of fields in the table. int Append(); Appends the contents of the record transfer buffer to the end of the table. Returns the Paradox Engine result code. int Update(); Updates the current record with the contents of the record transfer buffer. Returns the Paradox Engine result code. int RecGet(); Places the contents of the current record into the record transfer buffer. Returns the Paradox Engine result code. int Insert(); Inserts a new record into the table using the contents of the record transfer buffer. Returns the Paradox Engine result code. int Empty(); Empties the contents of the record transfer buffer. Returns the Paradox Engine result code. int Delete(); Deletes the current record from the table. The current record pointer can be moved by an object of either the PXTABLE class or the PXRECORD class, so use caution. RECORDNUMBER RecNum(); Returns the current record number. int Goto(RECORDNUMBER recnum); Moves the current record pointer to the specified record number. Returns the Paradox Engine result code. int First(); Moves the current record pointer to the first record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. int Last(); Moves the current record pointer to the last record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. int Next(); Moves the current record pointer to the next record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. int Prev(); Moves the current record pointer to the previous record in the table. The current record pointer can be moved with either the PXTABLE class or the PXRECORD class, so use caution. Returns the Paradox Engine result code. int SrchFld(PXFIELD &field, int scope = SEARCHFIRST); Searches the specified field using the contents of the record transfer buffer. Optionally, you may specify a FIELDHANDLE instead of a PXFIELD object. Returns the Paradox Engine result code. int SrchKey(int nFlds, int scope = SEARCHFIRST) Searches using the specified number of key fields and the contents of the record transfer buffer. Returns the Paradox Engine result code. int Put(PXFIELD &field); Puts a blank into the specified field of the record transfer buffer. You may optionally specify a FIELDHANDLE instead of a PXFIELD object. Returns the Paradox Engine result code. int Put(PXFIELD &field, short s); Puts a short integer into the specified field of the record transfer buffer. You may optionally specify a FIELDHANDLE instead of a PXFIELD object. Returns the Paradox Engine result code. int Put(PXFIELD &field, long l); Puts either a long integer or a date into the specified field of the record transfer buffer. You may optionally specify a FIELDHANDLE instead of a PXFIELD object. Returns the Paradox Engine result code. int Put(PXFIELD &field, double d); Puts a double into the specified field of the record transfer buffer. You may optionally specify a FIELDHANDLE instead of a PXFIELD object. Returns the Paradox Engine result code. int Put(PXFIELD &fiekd, int m, int d, int y); Puts a date into the specified field of the record transfer buffer. You may optionally specify a FIELDHANDLE instead of a PXFIELD object. Returns the Paradox Engine result code. int Put(PXFIELD &field, char *a); Puts a string into the specified field of the record transfer buffer. You may optionally specify a FIELDHANDLE instead of a PXFIELD object. Returns the Paradox Engine result code. int Get(PXFIELD &field, short &s); int Get(PXFIELD &field, long &l); int Get(PXFIELD &field, double &d); int Get(PXFIELD &field, int bufSize, char *a); int Get(PXFIELD &field, int &m, int &d, int &y); Retreives the contents of the specified field from the record transfer buffer. You may optionally specify a FIELDHANDLE instead of a PXFIELD object. Specify a reference to a long integer for either a numeric field or a date field. Returns the Paradox Engine result code. Operators: Operator =(PXRECORD &sourceRec); Use the assignment operator to copy the contents of one record transfer buffer to another. The two record transfer buffers do not need to be tied to the same table, but the structure of the tables must be identical. Class PXLOCK Each object of this class represents a lock on a record in the specified table. A PXLOCK can constructed using either a PXTABLE object or a PXRECORD object. In either case the lock is placed on the current record in the table. Be sure to test for success after creating a PXLOCK object. A lock may be removed by the destruction of the object or by using the Unlock() method. Constructors: PXLOCK(PXTABLE &pxtable); Places a lock on the current record in the specified table. PXLOCK(PXRECORD &pxrecord); Places a lock on the current record in the table associated with the PXRECORD object. Methods: LOCKHANDLE LockHandle(); Returns the lock handle of the object. int Unlock(); Attempts to remove the lock. Returns the Paradox Engine result code. int Goto(); Moves the current record pointer to the locked record. Returns the Paradox Engine result code. Using PDXPP All you need is PDXPP.H. Just include it in your source code and use it. All functions and methods are inline. It is not necessary to include PXENGTCL.H as well. Sample Program #include #include "pdxpp.h" void main() { if(PXInit() != PXSUCCESS) { cout << "Unable to initialize the engine!"; exit(1); } PXTABLE payments("payments"); if(!payments) { cout << "Unable to open table."; exit(1); } PXRECORD rtb(payments); PXFIELD fInvNum(payments, "Inv #"); PXFIELD fAmount(payments, "amount"); PXFIELD fCheckDate(payments, "Check Date"); PXFIELD fCheckNum(payments, "Check #"); short invNum; long checkNum; int m,d,y; double amount; for(rtb.First(); rtb; rtb.Next()) { rtb.Get(fInvNum, invNum); rtb.Get(fAmount, amount); rtb.Get(fCheckDate, m, d, y); rtb.Get(fCheckNum, checkNum); cout << invNum << fCheckNum << m << d << y%100 << amount; cout << nl; } PXExit(); } Appendix 1: Paradox Engine Functions not represented. PXExit PXGetDefaults PXInit PXKeyAdd PXKeyDrop PXNetErrUser PXNetInit PXNetUserName PXPswAdd PXPswDel PXSetDefaults PXSetHWHandler PXTblAdd PXTblCopy PXTblDecrypt PXTblDelete PXTblEmpty PXTblEncrypt PXTblExist PXTblMaxSize PXTblProtected PXTblRename ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 3,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.